db: reuse prepared statements via a per-connection cache - #61

What this does (plain English)

pi-prospector talks to a small local database that stores your analysis. Every time it wanted to ask the database a question, it would re-teach the database the full wording of that question from scratch — thousands of times in a single run, even for the same question repeated over and over. Repeating that teaching step (SQLite calls it "preparing" a statement) is busier than it looks.

This change lets the program remember each question it has already taught, so repeated questions reuse the remembered version instead of re-teaching it every time. It is pure housekeeping: the answers it gets are exactly the same — it just stops doing the same setup work repeatedly.

Technical detail

Nearly every db access went through db.prepare(), so SQLite re-parsed and re-planned each statement on every call (db.cache is undefined in better-sqlite3). This adds a per-connection prepared-statement cache and routes the hot helpers through it:

• src/db/statement-cache.ts — a WeakMap<Database, Map<sql, Statement>>. The cache is keyed by the Database instance because a better-sqlite3 Statement is bound to the connection it was prepared on; a module-global SQL→Statement map would hand a statement from a closed temp database to the next test.
• prepare(db, sql) returns the cached statement for that connection, preparing once and reusing afterwards. Only connections that have run migrate() (and therefore carry the final schema) ever store; a raw connection that skipped migrate() still executes but caches nothing — so it is purely an optimisation and never changes behaviour.
• initializeStatementCache(db) is called as the final step of migrate(), tying cache lifetime to the connection after schema migration. A statement is never compiled against pre-migration schema.
• Routed queries.ts, analysis-queries.ts, and the framework's hot db_loadMessages (the sanity check the issue asks for).

Correctness / no-behaviour-change verification

• npm test: 441 passed, 0 failed (unit + component, mock LLM).
• Integration (test/integration/test-commands.ts): 21 passed, 0 failed — full sync→analyze→proposal flow, idempotent re-runs, revise-mode lineage, proposal lifecycle, prospect verify.
• tsc --noEmit clean.
• New focused suite tests/component/statement-cache.test.ts covers: same statement reused for identical SQL on a connection; statements not shared across connections (a closed connection's cached statement is never handed to another); uninitialized connections still execute but don't cache; migrate() initializes the cache.

Measurement (exactly what and against what)

Measured on this branch's code vs raw per-call db.prepare on the same connection, fresh scratch SQLite DB under /tmp, 200,000 bound lookups of a simple indexed query:

• cached (helper): ~1565 ms; per-call db.prepare: ~1910 ms → ~1.2×.

This compares the statement-reuse effect directly against main's per-call behaviour on the same connection, so it does not double-count #55 (that PR batched node+edge writes into a single db.transaction(), which is orthogonal). It is not a headline speedup: the whole write path is a fraction of a percent of wall time on a real corpus, and this change is framed as hygiene, not as a wall-time target.

— quiet-sloth-61